Inside Macintosh: Imaging with QuickDraw
Use the GetGWorldPixMap function to obtain a handle to the PixMap record for an offscreen graphics world. You can then pass this handle, which is of data type PixMapHandle , in parameters to several routines that allow you to manage an offscreen graphics world's pixel image.
To prevent the base address for an offscreen pixel image from being moved (while you draw into or copy from its pixel map, for example), pass its handle to the LockPixels function. When you are finished drawing into or copying from an offscreen pixel map, pass its handle to the UnlockPixels procedure.
You can use the AllowPurgePixels procedure to make the base address for an offscreen pixel image purgeable. To prevent the Memory Manager from purging the base address for an offscreen pixel map, use the NoPurgePixels procedure.
To save the current information about the memory allocated for an offscreen pixel image, you can use the GetPixelsState function. To restore this state, you can use the SetPixelsState procedure.
You can use the GetPixBaseAddr function to obtain a pointer to the beginning of a pixel image in memory. You can use the PixMap32Bit function to determine whether a pixel map requires 32-bit addressing mode for access to its pixel image.
Use the GetGWorldPixMap function to obtain the pixel map created for an offscreen graphics world.
FUNCTION GetGWorldPixMap (offscreenGWorld: GWorldPtr):
PixMapHandle;
The GetGWorldPixMap function returns a handle to the pixel map created for an offscreen graphics world. In the offscreenGWorld parameter, pass the pointer returned to your application by the NewGWorld function when you created the offscreen graphics world. Your application can, in turn, pass the handle returned by GetGWorldPixMap as a parameter to other QuickDraw routines that accept a handle to a pixel map.
On a system running only basic QuickDraw, the GetGWorldPixMap function returns the handle to a 1-bit pixel map that your application can supply as a parameter to the other routines related to offscreen graphics worlds. However, your application should not supply this handle to Color QuickDraw routines.
To ensure compatibility on systems running basic QuickDraw instead of Color QuickDraw, use GetGWorldPixMap whenever you need to gain access to the bitmap created for a graphics world--that is, do not dereference the GWorldPtr record for that graphics world.
The GetGWorldPixMap function is not available in systems preceding System 7. You can make sure that the GetGWorldPixMap function is available by using the Gestalt function with the gestaltSystemVersion selector. Test the low-order word in the response parameter; if the value is $0700 or greater, then GetGWorldPixMap is available.
To prevent the base address for an offscreen pixel image from being moved while you draw into or copy from its pixel map, use the LockPixels function.
FUNCTION LockPixels (pm: PixMapHandle): Boolean;
The LockPixels function prevents the base address for an offscreen pixel image from being moved. You must call LockPixels before drawing to or copying from an offscreen graphics world.
The baseAddr field of the PixMap record for an offscreen graphics world contains a handle instead of a pointer (which is what the baseAddr field for an onscreen pixel map contains). The LockPixels function dereferences the PixMap handle into a pointer. When you use the UnlockPixels procedure, which is described next, the handle is recovered.
If the base address for an offscreen pixel image hasn't been purged by the Memory Manager or is not purgeable, LockPixels returns TRUE as its function result, and your application can draw into or copy from the offscreen pixel map. However, if the base address for an offscreen pixel image has been purged, LockPixels returns FALSE to indicate that you can perform no drawing to or copying from the pixel map. At that point, your application should either call the UpdateGWorld function (described on UpdateGWorld ) to reallocate the offscreen pixel image and then reconstruct it, or draw directly in a window instead of preparing the image in an offscreen graphics world.
As soon as you are finished drawing into and copying from the offscreen pixel image, you should call the UnlockPixels procedure.
The LockPixels function may move or purge memory blocks in the application heap. Your application should not call this function at interrupt time.
Listing 6-1 and Listing 6-2 illustrate the use of this function. See Inside Macintosh: Memory for more information about memory management.
When you are finished drawing into and copying from an offscreen graphics world, use the UnlockPixels procedure.
PROCEDURE UnlockPixels (pm: PixMapHandle);
The UnlockPixels procedure allows the Memory Manager to move the base address for the offscreen pixel map that you specify in the pm parameter. To ensure the integrity of the data in a pixel image, call LockPixels (explained in the preceding section) before drawing into or copying from a pixel map; then, to prevent heap fragmentation, call UnlockPixels as soon as your application finishes drawing to and copying from the offscreen pixel map.
The baseAddr field of the PixMap record for an offscreen graphics world contains a handle instead of a pointer (which is what the baseAddr field for an onscreen pixel map contains). The LockPixels function dereferences the PixMap handle into a pointer. When you use the UnlockPixels procedure, the handle is recovered.
You don't need to call UnlockPixels if LockPixels returns FALSE , because LockPixels doesn't lock the memory for a pixel image if that memory has been purged. However, calling UnlockPixels on purged memory does no harm.
You can use the AllowPurgePixels procedure to make the base address for an offscreen pixel image purgeable.
PROCEDURE AllowPurgePixels (pm: PixMapHandle);
The AllowPurgePixels procedure marks the base address for an offscreen pixel image as purgeable; this allows the Memory Manager to free the memory it occupies if available memory space becomes low. By default, NewGWorld creates an unpurgeable base address for an offscreen pixel image.
To get a handle to an offscreen pixel map, first use the GetGWorldPixMap function, described on GetGWorldPixMap . Then supply this handle for the pm parameter of AllowPurgePixels .
Your application should call the LockPixels function (described on LockPixels ) before drawing into or copying from an offscreen pixel map. If the Memory Manager has purged the base address for its pixel image, LockPixels returns FALSE . In that case either your application should use the UpdateGWorld function (described on UpdateGWorld ) to begin reconstructing the offscreen pixel image, or it should draw directly to an onscreen graphics port.
Only unlocked memory blocks can be made purgeable. If you use LockPixels , you must use the UnlockPixels procedure (explained in the preceding section) before calling AllowPurgePixels .
The AllowPurgePixels procedure may move or purge memory blocks in the application heap. Your application should not call this procedure at interrupt time.
To prevent the Memory Manager from purging the base address for an offscreen pixel image, use the NoPurgePixels procedure.
PROCEDURE NoPurgePixels (pm: PixMapHandle);
The NoPurgePixels procedure marks the base address for an offscreen pixel image as unpurgeable. To get a handle to an offscreen pixel map, use the GetGWorldPixMap function, described on GetGWorldPixMap . Then supply this handle for the pm parameter of NoPurgePixels .
To save the current information about the memory allocated for an offscreen pixel image, you can use the GetPixelsState function.
FUNCTION GetPixelsState (pm: PixMapHandle): GWorldFlags;
The GetPixelsState function returns information about the memory allocated for the base address for an offscreen pixel image. This information can be either of the following flags defined by the GWorldFlags data type:
TYPE GWorldFlags =
SET OF ( {flags for GetPixelsState only are listed here}
pixelsPurgeable, {the base address for an offscreen pixel }
{ image is purgeable}
pixelsLocked, {the offscreen pixel image is locked and }
{ not purgeable}
);
If the pixelsPurgeable flag is not returned, then the base address for the offscreen pixel image is unpurgeable. If the pixelsLocked flag is not returned, then the base address for the offscreen pixel image is unlocked.
After using GetPixelsState to save this state information, your application can later use the SetPixelsState procedure, described next, to restore this state to the offscreen graphics world.
Specify a handle to a pixel map in the pm parameter. To get a handle to an offscreen pixel map, use the GetGWorldPixMap function, described on GetGWorldPixMap .
The GetPixelsState function may move or purge memory blocks in the application heap. Your application should not call this function at interrupt time.
The trap macro and routine selector for the GetPixelsState function are
After using GetPixelsState and before using SetPixelsState , your application can temporarily use the AllowPurgePixels procedure (described on AllowPurgePixels ) to make the base address for an offscreen pixel image purgeable, the NoPurgePixels procedure (described on NoPurgePixels ) to make it unpurgeable, the LockPixels function (described on LockPixels ) to prevent it from being moved, and the UnlockPixels procedure (described on UnlockPixels ) to allow it to be moved.
To restore an offscreen pixel image to the state that you saved with the GetPixelsState function (explained in the preceding section), you can use the SetPixelsState procedure.
PROCEDURE SetPixelsState (pm: PixMapHandle; state: GWorldFlags);
TYPE GWorldFlags =
SET OF ( {flags for SetPixelsState are listed here}
pixelsPurgeable, {make the base address for an }
{ offscreen pixel image purgeable}
pixelsLocked {prevent the base address for an }
{ offscreen pixel image from }
{ being moved}
);
The SetPixelsState procedure changes the state of the memory allocated for an offscreen pixel image to the state indicated by the flags specified in the state parameter, which you typically save using the GetPixelsState function.
Because only an unlocked memory block can be purged, SetPixelsState calls the UnlockPixels and AllowPurgePixels procedures (described on UnlockPixels and AllowPurgePixels , respectively) if the state parameter specifies the pixelsPurgeable flag. If the state parameter does not specify the pixelsPurgeable flag, SetPixelsState makes the base address for the offscreen pixel image unpurgeable.
If the state parameter does not specify the pixelsLocked flag, SetPixelsState allows the base address for the offscreen pixel image to be moved.
The SetPixelsState procedure may move or purge memory blocks in the application heap. Your application should not call this procedure at interrupt time.
The trap macro and routine selector for the SetPixelsState procedure are
After using GetPixelsState and before using SetPixelsState , your application can temporarily alter the offscreen graphics world by using the AllowPurgePixels procedure (described on AllowPurgePixels ) to temporarily mark the memory block for its offscreen pixel map as purgeable, the NoPurgePixels procedure (described on NoPurgePixels ) to make it unpurgeable, the LockPixels function (described on LockPixels ) to prevent it from being moved, and the UnlockPixels procedure (described on UnlockPixels ) to unlock it.
You can use the GetPixBaseAddr function to obtain a pointer to an offscreen pixel map.
FUNCTION GetPixBaseAddr (pm: PixMapHandle): Ptr;
The GetPixBaseAddr function returns a 32-bit pointer to the beginning of a pixel image. The baseAddr field of the PixMap record for an offscreen graphics world contains a handle instead of a pointer, which is what the baseAddr field for an onscreen pixel map contains. You must use the GetPixBaseAddr function to obtain a pointer to the PixMap record for an offscreen graphics world.
Your application should never directly access the baseAddr field of the PixMap record for an offscreen graphics world; instead, your application should always use GetPixBaseAddr . If your application is using 24-bit mode, your application should then use the PixMap32Bit function (described next) to determine whether a pixel map requires 32-bit addressing mode for access to its pixel image.
If the offscreen buffer has been purged, GetPixBaseAddr returns NIL .
Any QuickDraw routines that your application uses after calling GetPixBaseAddr may change the base address for the offscreen pixel image.
The GetPixBaseAddr function may move or purge memory blocks in the application heap. Your application should not call this function at interrupt time.
You can use the PixMap32Bit function to determine whether a pixel map requires 32-bit addressing mode for access to its pixel image.
FUNCTION PixMap32Bit (pmHandle: PixMapHandle): Boolean;
The PixMap32Bit function returns TRUE if a pixel map requires 32-bit addressing mode for access to its pixel image. If your application is in 24-bit mode, you must change to 32-bit mode.
To get a handle to an offscreen pixel map, first use the GetGWorldPixMap function, described on GetGWorldPixMap . Then supply this handle for the pm parameter of PixMap32Bit .